home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
SGI Freeware 2002 November
/
SGI Freeware 2002 November - Disc 2.iso
/
dist
/
fw_hylafax.idb
/
usr
/
freeware
/
catman
/
u_man
/
cat1
/
faxmail.Z
/
faxmail
Wrap
Text File
|
2002-07-08
|
25KB
|
506 lines
FAXMAIL(1) FAXMAIL(1)
NNAAMMEE
faxmail - _H_y_l_a_F_A_X mail-to-fax gateway application
SSYYNNOOPPSSIISS
ffaaxxmmaaiill [ _o_p_t_i_o_n_s ] [ _d_e_s_t_i_n_a_t_i_o_n [ _f_r_o_m ] ]
DDEESSCCRRIIPPTTIIOONN
_f_a_x_m_a_i_l takes an electronic mail message on standard input
and converts it to POSTSCRIPT in a form that is suitable
for transmission as a facsimile. The converted document
is either written to the standard output or, if direct
delivery is enabled, it is submitted directly to a _H_y_l_a_F_A_X
server for transmission.
_f_a_x_m_a_i_l is designed for use in constructing electronic
mail to facsimile gateway services. For example, mail
aliases may be created to automatically transmit elec
tronic mail; e.g.
sam: "|${BIN}/faxmail -d sam@5551212"
or _f_a_x_m_a_i_l may be used as a ``mail transport agent'',
extracting the necessary delivery information directly
from the envelope of the mail message.
If _f_a_x_m_a_i_l is invoked without enabling direct delivery
then it just formats the mail message on the standard
input and writes the result to the standard output. To
enable direct delivery the --dd option must be specified on
the command line; see below for more information.
FFOORRMMAATTTTIINNGG
_f_a_x_m_a_i_l formats a mail message according to the following
rules: First it parses the envelope information interpret
ing any meta-header information (see below) that is pre
sent. Once the entire envelope has been collected it
emits a formatted set of header lines. By default all
header information except the ``From'', ``To'', ``Cc'',
``Subject'', and ``Date'' lines are discarded. Header
lines that are kept have the _t_a_g (the string to the left
of the ``:'') set in a _b_o_l_d _f_o_n_t and the _v_a_l_u_e (the string
to the right of the ``:'') set in an _i_t_a_l_i_c _f_o_n_t. Mail
messages that conform to the Multipurpose Internet Mail
Extensions (MIME) specification are parsed and handled
according to the rules given below. Plain text body parts
of a mail message are formatted in a _t_e_x_t _f_o_n_t with any
long lines wrapped at word boundaries unless the --cc option
has been specified.
By default, _f_a_x_m_a_i_l sets all text in 10 point type on an
8.5" by 11" portrait-oriented page with .35" top margin,
.25" bottom margin and .25" left and right hand margins.
There are command-line options to control the point size,
page dimensions, orientation, and multi-column formatting.
Text formatting can also be controlled through meta-header
directives placed in the envelope of the mail message.
EENNVVEELLOOPPEE PPRROOCCEESSSSIINNGG
_f_a_x_m_a_i_l pre-processes the envelope information (i.e. the
header lines) before formatting the message contents.
Header lines whose names begin with ``X-FAX-'' (case-
insensitive) are handled specially-they are treated as
command directives that specify how to generate the
resultant POSTSCRIPT or, optionally, how to deliver the
resulting document as facsimile. The set of known meta-
headers corresponds to the set of configuration parameters
defined below. A meta-header is specified as ``X-FAX-
_p_a_r_a_m_e_t_e_r'' where _p_a_r_a_m_e_t_e_r is the name of a configuration
parameter; e.g. ``X-FAX-TabStop'' to set the number of
spaces between tab stops.
Controls for specifying headers to be passed through in
the formatted text identify not only which headers but
also the order in which the headers should be emitted.
_f_a_x_m_a_i_l initializes the set of headers to retain to: ``To
From Subject Cc Date''. If this order is acceptable then
additional headers can simply be added with the X-FAX-
Headers directive; e.g. ``X-FAX-Headers: Message-id''. If
however a different order is desired then the header set
should be cleared with a ``clear'' header tag and then
completely specified in the desired order; for example,
X-FAX-Headers: clear Message-id Date To Subject From Cc
will cause headers to be emitted in the order ``Message-Id
Date To Subject From Cc'' (depending on what headers are
present). Note in particular that all header lines in the
envelope can be suppressed by specifying ``X-FAX-Headers:
clear''; this is useful, for example, when the body of the
mail message contains a preformatted document that is to
be transmitted.
In addition to the above controls, _f_a_x_m_a_i_l can also be
instructed to substitute an arbitrary string for a header
tag when generating the final envelope. This facility can
be used to better format ad-hoc header information that is
passed through the envelope of the message. The ``X-FAX-
MapHeader'' meta-header specifies how to map a header
line. For example,
X-FAX-MapHeader: x_FAX_For Deliver FAX To
would cause any header ``x_FAX_For'' that appeared in the
envelope to be replaced in the formatted envelope by
``Deliver FAX To''.
MMIIMMEE PPRROOCCEESSSSIINNGG
_f_a_x_m_a_i_l parses MIME mail messages and does some rudimen
tary work to:
strip out unprintable content such as audio, video, or
binary data,
decode encoded parts,
insert ``digest dividers'' between multipart/digest
subparts,
format message/rfc822 parts as described above for the
top-level envelope, and
optionally convert graphical parts (e.g. images) for
display.
MIME processing is fairly simple and (currently) somewhat
constrained. _f_a_x_m_a_i_l has builtin support for the follow
ing MIME parts: text/plain, multipart/mixed, multi
part/digest, message/rfc822, application/postscript, and
application/x-faxmail-prolog. Parts can also be processed
through external processing scripts that _f_a_x_m_a_i_l looks for
in a ``MIME converters'' directory hierarchy. External
scripts may override builtin processing or supplement the
builtin support. For each MIME body part with type _T and
subtype _S _f_a_x_m_a_i_l checks first for an executable script
named T/S in the converter hierarchy. If a script exists
then it is run and the result is appended to the output
PostScript document. Otherwise if the part has builtin
support then it is processed directly. Any part that does
not have external or builtin support is discarded and
replaced by a message that indicates the part was removed.
This discarded message can be suppressed with the _M_a_r_k_D_i_s_
_c_a_r_d_e_d configuration parameter (also settable with an X-
FAX-MarkDiscarded line in the envelope).
The builtin handling support is as follows: text/plain
parts are formatted using the default _t_e_x_t _f_o_n_t and point
size; multipart/mixed are ``burst'' and interpreted per
the specification but are otherwise unformatted; multi
part/digest are burst and an optional ``digest divider''
marking may be inserted before each subpart; mes
sage/rfc822 are formatted as described above with envelope
header lines culled and formatted with bold and italic
fonts (in addition, if there is insufficient space in the
current output page/column for the message envelope,
optional divider, and one line of text, then _f_a_x_m_a_i_l will
insert a ``break'' so the the message starts at the top of
the next page/column); application/postscript are copied
through untouched to the output; application/x-faxmail-
prolog are copied through untouched to the end of the pro
logue section of the generated PostScript document to per
mit customization of the formatted output.
_f_a_x_m_a_i_l supports the following Content-Transfer-Encoding
schemes: 7bit, 8bit, binary, base64, quoted-printable, and
x-uuencode. Any character set that is not us-ascii is
treated as iso-8859-1.
In general it is recommended that senders either permit
_f_a_x_m_a_i_l to format message contents or completely bypass
the formatting facilities and submit data that is to be
processed by _s_e_n_d_f_a_x. Trying to combine the two facili
ties by, for example, combining PostScript with text that
is to be formatted is unlikely to work well because _f_a_x_
_m_a_i_l does not track the amount of space on the page that a
non-text MIME part uses.
DDIIRREECCTT DDEELLIIVVEERRYY
When _f_a_x_m_a_i_l is invoked with the --dd option it delivers the
formatted document directly to a _H_y_l_a_F_A_X server for trans
mission as facsimile. Command line arguments may be sup
plied to specify the delivery destination and sender iden
tity; typically from information extracted by the mail
transport facility. A command line _d_e_s_t_i_n_a_t_i_o_n is speci
fied with the same syntax as the argument for the --dd
option to the _s_e_n_d_f_a_x(1) command. Similarly any _f_r_o_m
identity specified on the command line follows the same
rules as the --ff option to _s_e_n_d_f_a_x. An explicit dialstring
to use in delivery can also be specified with an X-FAX-
Dialstring header in the mail message envelope. If no
sender identity is provided on the command line then _f_a_x_
_m_a_i_l will extract it from the ``From'' line in the enve
lope. _f_a_x_m_a_i_l will not submit a message for delivery if
either the dialstring or sender identity is missing or
null.
When direct delivery is enabled X-FAX- header lines may be
included in the mail message envelope to control the sub
mission and delivery process. As above these lines are
specified as ``X-FAX-_p_a_r_a_m_e_t_e_r'' where _p_a_r_a_m_e_t_e_r is the
name of a configuration parameter for the _s_e_n_d_f_a_x program;
e.g. ``X-FAX-VRes'' to set the vertical resolution of the
transmitted facsimile. By default automatic cover page
generation is enabled when direct delivery is used; this
can be overridden with the --nn option on the command line
or by including an X-FAX-AutoCoverPage header in the mes
sage envelope.
OOPPTTIIOONNSS
--11 Set text in one column (default).
--22 Set text two columns.
--bb _f_o_n_t Make _f_o_n_t, a POSTSCRIPT font name, the ``_b_o_l_d
_f_o_n_t'' used to set header lines. The default
bold font is Helvetica-Bold.
--cc Clip long text lines instead of wrapping them at
page margins.
--dd Enable direct delivery of facsimile; the format
ted document will be submitted directly to a
_H_y_l_a_F_A_X server for transmission as facsimile.
This option is similar to piping the output of
_f_a_x_m_a_i_l to the input of _s_e_n_d_f_a_x(${MANNUM1_8})
except when direct delivery is enabled _f_a_x_m_a_i_l
interprets ``x-fax-'' header lines in the enve
lope of the mail message to look for control
information to use in delivering the facsimile
and, by default, no automatic cover page genera
tion is done.
--ff _f_o_n_t Make _f_o_n_t, a POSTSCRIPT font name, the text font
used to set the body of mail messages. The
default text font is Courier.
--HH _h_e_i_g_h_t Use _h_e_i_g_h_t as the height, in inches, of the out
put page. The default page height is taken from
the default page size.
--ii _f_o_n_t Make _f_o_n_t, a POSTSCRIPT font name, the ``_i_t_a_l_i_c
_f_o_n_t'' used to set header lines. The default
italic font is Helvetica-Oblique.
--MMll==_#_,rr==_#_,tt==_#_,bb==_#
Set the page margins; the default margins are:
left and right .25 inch, top .35 inch, bottom
.25 inch.
--nn Suppress auto cover page generation when doing
direct delivery.
--pp _s_i_z_e Set all text using _s_i_z_e for the font point size.
--rr Set pages rotated by 90 degrees (in ``Landscape
mode'').
--RR Set pages unrotated (in ``Portrait mode'').
--ss _s_i_z_e Set the page size to use. Cover pages are nor
mally generated using a system-default page size
(usually letter-size pages, 8.5" by 11", for
sites in North America). Alternate page sizes
are specified symbolically using either the name
or abbreviation of an entry in the _p_a_g_e_
_s_i_z_e_s(${MANNUM4_5}) database; e.g. _a_3 (ISO A3),
_a_4 (ISO A4), _a_5 (ISO A5), _a_6 (ISO A6), _b_4 (ISO
B4), _n_a_-_l_e_t (North American Letter), _u_s_-_l_e_g
(American Legal), _u_s_-_l_e_d (American Ledger), _u_s_-
_e_x_e (American Executive), _j_p_-_l_e_t (Japanese Let
ter), and _j_p_-_l_e_g (Japanese Legal). Comparisons
are case-insensitive and any match of a sub
string of the full page-size name is sufficient;
e.g. ``legal'' would match ``American Legal''.
--uu _u_s_e_r Set the user name to use when logging in to do
direct delivery. By default the user is speci
fied by the MMaaiillUUsseerr configuration parameter
(see below). If a null user name is specified,
then the facsimile will be submitted using the
identity of the user that invoked _f_a_x_m_a_i_l.
--vv Enable tracing of envelope, MIME, and job sub
mission processing. Diagnostic information is
written to the standard error (envelope and MIME
processing) and standard output (job submis
sion).
--WW _w_i_d_t_h Use _w_i_d_t_h as the width, in inches, of the output
page. The default page width is taken from the
default page size.
CCOONNFFIIGGUURRAATTIIOONN PPAARRAAMMEETTEERRSS
_f_a_x_m_a_i_l reads configuration information from the files
$${{LLIIBBDDAATTAA}}//hhyyllaa..ccoonnff, and ~~//..hhyyllaarrcc; in that order. Con
figuration files follow the conventions described in
_h_y_l_a_f_a_x_-_c_l_i_e_n_t(1). The following configuration parameters
are recognized:
TTaagg TTyyppee DDeeffaauulltt DDeessccrriippttiioonn
AutoCoverPage boolean Yes automatically generate cover page
BoldFont string Helvetica-Bold font for setting header tags
Columns integer 1 number of columns in formatted output
DigestDivider string - multipart/digest divider POSTSCRIPT command
FontPath string _s_e_e _b_e_l_o_w directory for font metric files
GaudyHeaders boolean No enable/disable gaudy page headers
Headers string _s_e_e _b_e_l_o_w headers to retain in envelope
ISO8859 boolean Yes use ISO 8859-1 character encoding
ItalicFont string Helvetica-Oblique font for setting header values
LineWrap boolean Yes wrap/truncate text lines
MailUser string - user identity for doing direct delivery
MarkDiscarded boolean Yes mark discarded MIME body parts
MapHeader string - define header mapping
MIMEConverters string _s_e_e _b_e_l_o_w pathname of MIME converter scripts
Orientation string portrait orientation of text on page
OutlineMargin inches 0 width of outline line
PageCollation string forward collate pages in forward or reverse direction
PageHeaders boolean Yes enable/disable page headers
PageHeight float - output page height
PageMargins string _s_e_e _b_e_l_o_w margins for formatted page
PageSize string default output page size from database
PageWidth float - output page width
Prologfile string _s_e_e _b_e_l_o_w pathname of POSTSCRIPT prologue file
TabStop integer 8 inter-stop setting in characters
TextFont string Courier name of font for setting text
TextLineHeight inches - text formatting line height control
TextPointSize inches _s_e_e _b_e_l_o_w size to use in setting text
Verbose boolean No trace envelope and MIME processing
Values marked as _i_n_c_h_e_s are specified using a syntax that
identifies one of several possible units:
#.##bp big point (1in = 72bp)
#.##cc cicero (1cc = 12dd)
#.##cm centimeter
#.##dd didot point (1157dd = 1238pt)
#.##in inch
#.##mm millimeter (10mm = 1cm)
#.##pc pica (1pc = 12pt)
#.##pt point (72.27pt = 1in)
#.##sp scaled point (65536sp = 1pt)
Unit names can be upper or lower case but no white space
is permitted between the number and the unit. Values
specified with no unit are interpreted as points.
The configuration parameters are explained below. Most
parameters correspond to a command line option. Parameter
values identified above as _i_n_c_h_e_s are converted according
to the conventions described above.
AAuuttooCCoovveerrPPaaggee Control whether or not a cover page is
automatically generated for each job.
BBoollddFFoonntt The name of the font to use to set header
tags (i.e. the string to the left of the
``:'').
CCoolluummnnss The number of columns to set text in.
(Equivalent to the --mm option.)
DDiiggeessttDDiivviiddeerr The string to emit in the output before
each subpart of a multipart/digest mail
message. This string is typically a
POSTSCRIPT procedure that draws a mark of
some sort. Dividers are expected to use no
more vertical space on the output page than
a line of text.
FFoonnttPPaatthh The path where Adobe Font Metric (AFM)
files are located; by default ${FONTPATH}.
GGaauuddyyHHeeaaddeerrss Control whether or not to use a gaudy-style
page header. Enabling gaudy headers
implicitly enables page headers.
HHeeaaddeerrss Define the headers retained from the enve
lope and specify the order that they should
be emitted in the formatted output. The
set of headers is initialized to ``To From
Subject Cc Date''. Headers specified are
appended to this list except for a
``clear'' header that causes the current
set of headers to be discarded.
IISSOO88885599 Control the use of ISO 8859-1 encoding in
the generated POSTSCRIPT
IIttaalliiccFFoonntt The name of the font to use to set header
values (i.e. the string to the right of the
``:'').
LLiinneeWWrraapp Control whether long text lines are wrapper
or truncated at the right hand margin.
(Equivalent to the --cc option.)
MMaaiillUUsseerr The account name to use to login to a fax
server when doing direct delivery. Note
that this account name is not used for the
identity of the sender; this comes from the
command line or the ``From'' line in the
mail message. If a null account name is
specified, then the facsimile will be sub
mitted using the identity of the user that
invoked _f_a_x_m_a_i_l.
MMaappHHeeaaddeerr Define a substitution for the specified
header that should be done each time the
header is emitted in the formatted enve
lope. Header tags are matched in a case-
insensitive manner.
MMaarrkkDDiissccaarrddeedd Control whether discarded MIME parts are
replaced by a text message indicating the
original content was removed.
MMIIMMEECCoonnvveerrtteerrss The pathname of a directory hierarchy that
has scripts for external processing of MIME
body parts. The default pathname is
${LIBEXEC}/faxmail.
OOrriieennttaattiioonn Control whether pages are oriented horizon
tally (``landscape'') or vertically (``por
trait''). (Equivalent to the --rr and --RR
options.)
OOuuttlliinneeMMaarrggiinn Control whether columns of text have a line
drawn around them and the width of the
line. Setting this parameter to 0 disables
outlines.
PPaaggeeCCoollllaattiioonn Control whether the output file has pages
collated in the same order as the input
file (``forward'') or in reverse order
(``reverse).
PPaaggeeHHeeaaddeerrss Control whether page headers are generated.
PPaaggeeHHeeiigghhtt Set the output page height (in inches).
PPaaggeeMMaarrggiinnss Set the output page margins. Margins are
specified as string of the form:
``ll==#,rr==#,tt==#,bb==#'' where ll indicates the
left margin, rr indicates the right margin,
tt indicates the top margin, bb indicates the
bottom margin, and numbers are interpreted
as _i_n_c_h_e_s. (Equvalent to the --MM option.)
PPaaggeeSSiizzee Set the output page dimensions by name.
(Equivalent to the --ss option.)
PPaaggeeWWiiddtthh Set the output page width (in inches).
PPrroollooggFFiillee The pathname of a file containing
POSTSCRIPT that should be included in the
prologue section of the generated
POSTSCRIPT. The default prologue file is
${LIBDATA}/faxmail.ps.
TTaabbSSttoopp Set the tab stop distance (in characters).
TTeexxttFFoonntt Set the name of font to use for setting
text. (Equivalent to the --ff option.)
TTeexxttLLiinneeHHeeiigghhtt Set the vertical text line height and spac
ing.
TTeexxttPPooiinnttSSiizzee Set the point size to use in setting plain
text. (Equvalent to the --pp option.)
VVeerrbboossee Control tracing envelope and MIME process
ing.
NNOOTTEESS
Because a sender's identity in an electronic mail message
is inherently untrustworthy, using _f_a_x_m_a_i_l to build a mail
to fax gateway is problematic. Unless mail service is
somehow restricted or the sender's identity is verified
using a mechanism such as RFC 1847's multipart/signed MIME
type there is no reliable way to restrict access to facil
ities setup with _f_a_x_m_a_i_l.
BBUUGGSS
Only the last instance of a header is kept and written to
the output. This means, for example, that only the last
of many ``Received'' lines will be included in the format
ted output.
FFIILLEESS
~/.hylarc per-user configuration file
${LIBDATA}/pagesizes page size database
${LIBDATA}/faxmail.ps POSTSCRIPT prologue
${LIBDATA}/hyla.conf system-wide configuration file
${LIBDATA}/faxmail.conf system-wide configuration file
${LIBDATA}/sendfax.conf system-wide configuration file for direct delivery
${LIBEXEC}/faxmail hierarchy for external MIME converters
${FONTPATH} for font metrics
${SPOOL}/tmp/faxmailXXXXXX temporary files
SSEEEE AALLSSOO
_h_y_l_a_f_a_x_-_c_l_i_e_n_t(1), _t_e_x_t_f_m_t(1), _s_e_n_d_f_a_x(1)
July 22, 1996 FAXMAIL(1)